Git hands-on session within RStudio

Working on your own

Create a repo

1. Go to GitHub and login
2. Follow this tutorial to create a repo

Git for RStudio setup

1. Download and install Git
2. Install RStudio
3. Open RStudio

Git for RStudio setup

Tell RStudio where to find the Git installation.

1. Go to Tools > Global Options
2. Click on Git/SVN.

Git for RStudio setup

Check Enable version control interface for RStudio projects. Set the path to the Git executable that you just installed. Open a shell, if you don’t know where Git is installed. Type where git and hit enter (Windows users).

The path should be something like: C:/Program Files (x86)/Git/bin/git.exe

Git for RStudio setup: git configuration

1. Go to Tools > Shell to open the Git Shell
2. Tell Git your Github (!) username and GitHub email

Git for RStudio setup: git configuration

1. Go to Tools > Shell to open the Git Shell
2. Tell Git your Github (!) username and GitHub email:

In the shell, type the following two commands:

git config --global user.email "my.name@inbo.be"
git config --global user.name "mygithubusername"

Use your GitHub username!

Clone a repo to work locally

1. Copy the repository HTTPS url

2. File > New Project..., select Version Control, choose Git
3. Provide the repository HTTPS link, select desired directory

.gitignore

1. RStudio will always add .gitignore if it doesn’t exists
2. Go to git pane, right click .Proj and select Ìgnore
3. Update .gitignore and click Save. More details later.

Make a commit

1. Update the README.md
2. Commit your changes
3. Go to git pane, check .gitignore and click commit

Make a commit

1. Add a commit message and click commit

Make a commit

1. Click Close to remove the commit summary

Make a commit

1. Add a commit message and click commit

Push the changes to GitHub

1. Note that the git pane displays your branch is ahead of ‘origin/master’ by 2 commits
2. Click push in the git pane

Go to your repo on GitHub to verify

Store your credentials when using https

1. Click on the more button in the git pane and select shell
2. Type git config --global credential.helper store
3. Type exit to quit the shell
4. The next time git needs your credentials, it will ask them one more time and store them

Create logical commits

1. Make 2 unrelated changes to your README.md locally
2. Create one commit for each change.
3. Do NOT push (yet)

Create logical commits

1. Click Commit in the git pane
2. Select the changes you want to commit and click stage selection
3. Add a commit message and click Commit

Create logical commits

• stage xyz: add the xyz from the commit
• unstage xyz: remove the xyz from the commit
• discard xyz: revert the changes in the xyz (can’t be undone!!!)
• xyz can be
  • a single line
  • a selection of lines
  • a chunk
    • RStudio will automatically split the changes in chunks
    • chunks are defined by 10 unchanged lines between changes

Create a conflict

Update your README.md on GitHub,
on a line you also edited locally

Conflict!

Try to push (click push) your local changes

Keep calm and resolve conflict

1. Click Pull to download the changes from Github

Keep calm and resolve conflict

1. Open README.md in RStudio:

   <<<<<<< HEAD
   A simple analysis to visualize my favourite fruit colour.
   =======
   A simple analysis to discover my favourite fruit color.
   >>>>>>> origin/master

2. Choose what you want to keep:

   A simple analysis to discover my favourite fruit colour.

3. Commit and click push

Add a file

1. Add a fruits.csv file in a /data directory
2. Link to this file in the README.md

Add a file within a directory

• Staging a new directory will stage all files in the directory
• You can’t stage empty directories

Adapt last commit

• Warning: don’t do this on commits that have been pushed. That would result in conflicts.
• Make a change in fruits.csv
• Commit as usual but check amend previous commit under the commit message box

View history

• Click on history in the git pane

View history

Create a branch to experiment

1. Create a NEW branch
2. Add an analysis file in a /src directory
3. Commit
4. Switch between branches

Create a branch to experiment

1. Open the git shell

2. Create a branch by a checkout to new branch

   git checkout -b analysis-script

3. Get an overview of your branches: git branch

Effect of changing switching branches

Add a file to the repository in a src-directory (see earlier)

1. Go back to the status of the master branch
2. Click on analysis-script in the git pane and select (LOCAL BRANCHES) -> master

Effect of changing switching branches

1. Verify your local directory structure: where are your files?
2. Go back to the status of the new branch (e.g. analysis-script)
3. Verify your local directory structure again: where are your files?

First push of a new branch

1. Notice that the pull and push buttons in the git pane are grayed out
2. Open the Git Shell
3. Type git push -u origin analysis-script

This will also activate the pull and push buttons

Create a pull request to include your work

1. Click push
2. At Github, browse to you repo…
3. Create a pull request

Create a pull request to include your work

Create a pull request to include your work

Review your pull request

Review your pull request

1. Review
2. If OK, merge pull request
3. Delete branch

Include your accepted work to local master

1. Switch to master branch
2. Click pull.

Exclude files

• in any programming language, some files are derivatives
• sensitive information (passwords,…)
• a folder with large data files that should not be in the history (and backuped elsewhere!)
• a temp/ folder for just garbage you create/…

.gitignore to the rescue!

Exclude files

Note that you can use wild cards e.g. *.Rproj

Working together

Teaming up

• Team up with two or three persons
• Let one person invite the others, provide them with read/write access as explained in this tutorial

Invite collaborators

Invite collaborators

Collaboration: issues

• Raise an issue online
• Provide issues with an appropriate label
• Assign your colleague to the issue

Collaboration: online adaptations

• Make an adaptation to an online file
• Propose a pull request and assign your collaborator
• Merge the adaptation to the master branch

Collaboration: local adaptations

Working local - merging online

• As collaborator, clone the other repository to your local computer
• Create a new branch with a different name
• Adapt the content of a file
• commit your adaptation
• push your branch to the remote repository
• Go to GitHub and make a pull request
• Revise the work and merge online when appropriate
• Update your local work
• Check if all adaptations are represented in your local files

Tip: All functionalities are available in the previous sections

Release

Once you are satisfied with the status of your analysis, it makes sense to create a release:

• For publications (DOI)
• For code/software development versions
• For course notes

Follow this tutorial to create a release.

Some more advice:

• Commit often, make small commits
• Don’t mix changes in 1 commit
• Think about your commit messages
• Keep your code clean, avoid huge one-liners
• Use branches (!)
• Don’t keep long-lived branches (form of technical debt)

There’s no such thing, as a free lunch…

…but if you’re hungry:

• Webinars
  • Github and Rstudio management
  • Collaboration and time travel: version control with git, github and RStudio
• Tutorials
  • Hadley Wickham R packages book
  • Happy Git and GitHub for the useR

Information combined at INBO Tutorials website.
You’re welcome to provide issues, pull requests,…